////////////////////////////////////////////////
// DESCRIPTION:
//    Emulator Component control registration
//
// Legal Notices:
//   Copyright (c) 2008, Telliam Consulting, LLC.
//   All rights reserved.
//
//   Redistribution and use in source and binary forms, with or without modification,
//   are permitted provided that the following conditions are met:
//
//   * Redistributions of source code must retain the above copyright notice, this list
//     of conditions and the following disclaimer.
//   * Redistributions in binary form must reproduce the above copyright notice, this
//     list of conditions and the following disclaimer in the documentation and/or other
//     materials provided with the distribution.
//   * Neither the name of Telliam Consulting nor the names of its contributors may be
//     used to endorse or promote products derived from this software without specific
//     prior written permission.
//
//   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
//   EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
//   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
//   SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
//   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
//   TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 
//   BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
//   CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
//   ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
//   DAMAGE. 
//
using System;
using System.Text;
using System.Windows.Forms;
using System.Collections.Generic;

namespace FusionWare.SPOT.EmulatorComponents
{
    /// <summary>Interface implemented on Controls that wrap an emulator component</summary>
    /// <remarks>
    /// Controls that contain an emulator component must implement this interface so
    /// that any contained components (directly contained and/or child controls)
    /// are correctly registered with the emulation system. 
    /// 
    /// This allows a form derived from EmulatorForm to include controls that implement this
    /// interface and have all the emulator components automatically registered. This greatly
    /// simplifies the configuration of an emulator by making the connections automatically
    /// without the need to manually create and register components or specify them individually
    /// in an XML config file. 
    /// 
    /// DO NOT implement this interface on container controls unless they have an emulator
    /// component associated with the container. The EmulatorForm implementation of this
    /// interface will walk through all children recursively. This is to allow a form to
    /// contain a normal panel or other standard or third party container controls, which
    /// know nothing about this interface, and that control can further contain controls
    /// that implement this interface. Since we have no conrol of what types of container
    /// controls a UI designer might want to use this scheme allows complete flexibility. 
    /// </remarks>
    public interface IEmulatorComponentControl
    {
        /// <summary>Registers all child emulator components with the emulator</summary>
        /// <param name="Emulator">Emulator to register the components wit</param>
        /// <remarks>
        /// This method is used to register contained components with the emulation system
        /// </remarks>
        void RegisterComponents(CustomEmulator Emulator);
    }

    /// <summary>Static class containing utility funtions for implementing <see cref="IEmulatorComponentControl"/></summary>
    public static class IEmulatorComponentControlHelper
    {
        /// <summary>Recursively register all container children with the specified emulator</summary>
        /// <param name="Controls">Control collection to start search on</param>
        /// <param name="Emulator">Emulator to register components with</param>
        /// <remarks>
        /// This is used to recursivley register all child control components. The standard EmulatorForm
        /// calls this automatically in its implementation of the IEmulatorComponentControl interface
        /// However, UI designers might want to use some custom or third party derived form type so this
        /// allows code-reuse without requiring multiple inheritance, which is not supported in C#. When
        /// you can't use EmulatorForm as the base class for your UI forms you can implement the
        /// <see cref="IEmulatorComponentControl"/> interface and call this function from your 
        /// implementation of the RegisterComponents() interface method as shown in the example code 
        /// from the EmulatorForm implementation.
        /// </remarks>
        /// <example>
        /// Typical usage:
        /// <code source="..\Emulator\FusionWare.EmulatorComponents\EmulatorForm.cs" region="IEmulatorComponentControl Implementation" lang="cs" title="C#"/>
        /// </example>
        public static void RegisterComponents(Control.ControlCollection Controls, CustomEmulator Emulator)
        {
            if( Controls == null )
                throw new ArgumentNullException( "Controls" );

            if( Emulator == null )
                throw new ArgumentNullException( "Emulator" );

            foreach(Control c in Controls)
            {
                IEmulatorComponentControl iecc = c as IEmulatorComponentControl;
                if(iecc != null)
                    iecc.RegisterComponents(Emulator);
                else
                {
                    // if it's a conttainer then recursively process it's children
                    if(c.Controls != null && c.Controls.Count !=0 )
                        RegisterComponents(c.Controls, Emulator);
                }
            }
        }
    }
}
